support for legacy content collections removed #12376

sarah11918 · 2025-09-22T12:01:37Z

This adds "Removed: content collections" to the v6 upgrade guide

Direct deploy preview: https://deploy-preview-12376--astro-docs-2.netlify.app/en/guides/upgrade-to/v6/#removed-legacy-content-collections

Implementation PR #14407

This PR should include

Upgrade guide content for removal
Remove legacy flag docs
placeholder error messages so that links will work (both to them, and allow us to check links in them, if necessary)
- the content here doesn't have to be 100% accurate -- it will be overwritten with the JSDoc eventually
- I did not (yet?) bother to add these to the error index page as that will also be autogenerated and isn't needed for resolving or checking links
Check whether there are error messages for (then add to the details/summaries):
- NOT having any content config file at all
- calling entry.render()

Follow-up/concurrent tasks:

Proper error messages made at the source

Notes:

there should not be any new astro:content reference updated needed: v5 already only documents the newest API
any guide/reference changes will be handled along with Live Collections becoming stabilized (which will probably affect how we describe collections in general, and will bring larger docs needs around collections and API reference)
- let's not refer to "Content Layer API" anymore: going forward, we will have "collections" and "live collections"

netlify · 2025-09-22T12:02:39Z

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	`7f20e74`
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/68f6031ff7e363000875e64d
😎 Deploy Preview	https://deploy-preview-12376--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

astrobot-houston · 2025-09-22T12:03:13Z

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/upgrade-to/v6.mdx	Source changed, localizations will be marked as outdated.
en/reference/errors/content-collection-invalid-type.mdx	Localization added, will be marked as complete.
en/reference/errors/content-collection-missing-loader.mdx	Localization added, will be marked as complete.
en/reference/errors/legacy-content-config-error.mdx	Localization added, will be marked as complete.
en/reference/legacy-flags.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

src/content/docs/en/guides/upgrade-to/v6.mdx

ascorbic · 2025-09-24T18:41:20Z

src/content/docs/en/guides/upgrade-to/v6.mdx

+
+If you have content collections errors after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code.
+
+##### If you have...


We should add the error messages in here too

Yes, this could be helpful, or at least the error code so someone can easily identify the details to expand.

Great idea! Would the implementation PR be a comprehensive list of all the ones they might encounter?

I'm seeing:

'LegacyContentConfigError'

'ContentCollectionMissingLoader'

'ContentCollectionInvalidType'

What we did for v5 was mock up the new errors / config in the v5 branch (duplicating what would be generated from the JSDoc), so we should probabably manually recreate those errors in this PR, too. If they end up not being identical, then a ci PR will be generated to align them.

Just copied the entire jsdoc from entries here for now

@docs

@message

Example error message:

Found legacy content config file in "src/content/config.ts". Please move this file to "src/content.config.ts" and ensure each collection has a loader defined.

@description

A legacy content config file was found. Move the file to src/content.config.ts and update any collection definitions if needed.

See the Astro 6 migration guide for more information.
*/

export const LegacyContentConfigError = {
name: 'LegacyContentConfigError',
title: 'Legacy content config file found.',
message: (filename: string) =>
Found legacy content config file in "${filename}". Please move this file to "src/content.config.${filename.split('.').at(-1)}" and ensure each collection has a loader defined.,
hint: 'See https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections for more information on updating collections.',
} satisfies ErrorData;

/**

@docs

@message

Example error message:

Collections must have a loader defined. Check your collection definitions in your content config file.

@description

A content collection is missing a loader definition. Make sure that each collection in your content config file has a loader.

See the Content collections documentation for more information.
*/

export const ContentCollectionMissingLoader = {
name: 'ContentCollectionMissingLoader',
title: 'Content collection is missing a loader definition.',
message: (file = 'your content config file') =>
Collections must have a \loader` defined. Check your collection definitions in ${file}.`,
hint: 'See https://docs.astro.build/en/guides/content-collections/ for more information on content loaders and https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections for more information on migrating from legacy collections.',
} satisfies ErrorData;

/**

@docs

@message

Example error message:

Invalid collection type "data". Remove the type from your collection definition in your content config file.

@description

Content collections should no longer have a type field. Remove this field from your content config file.

See the Astro 6 migration guide for more information.
*/

export const ContentCollectionInvalidType = {
name: 'ContentCollectionInvalidType',
title: 'Content collection has an invalid type field.',
message: (type: string, file = 'your content config file') =>
Invalid collection type "${type}". Remove the type from your collection definition in ${file}.,
hint: 'See https://docs.astro.build/en/guides/upgrade-to/v6/#removed-legacy-content-collections for more information on migrating from legacy collections.',
} satisfies ErrorData;

There are also some places where we just log a warning rather than throwing an error:

https://github.com/withastro/astro/pull/14407/files#diff-04e44d3cde1db4d52d43a7732043f5239e1c49479b993e3dda7486399a5a51fbR214-R223

I could add a more searchable name there too.

I can't get to the spot in that link directly from the link, because GitHub can't handle the PR. 😅 Which file are warnings included in so I can get there myself?

OK, I've updated the text to refer to both error messages and warnings and we can do further edits on top of that!

I'm not sure they all need to be spelled out here, since in theory those should have their own explanations and guidance. To avoid this content being overwhelming, I think just a mention that "if you get warnings/errors, these are the likely places to check" is fine here! If people are not getting these errors/warnings, no need to be spelling them out.

I just meant adding the specific codes such as ContentCollectionMissingLoader to the section, to make each section more searchable

Ah, I think I get it. Let me cook!

OK, here's my current draft to address this:

@ascorbic I didn't notice specific errors (either in your removing legacy support PR, nor existing ones) for the situation where:

there is NO content config file at all

they are not importing and using the render function (and are instead calling it on the entry)

So, those two don't have associated errors mentioned here. Do we have such errors, and if not, should we?

src/content/docs/en/guides/upgrade-to/v6.mdx

ArmandPhilippot

A small nit, otherwise I think this format looks great and makes sense!

src/content/docs/en/guides/upgrade-to/v6.mdx

Co-authored-by: Matt Kane <[email protected]>

src/content/docs/en/reference/errors/content-collection-invalid-type.mdx

src/content/docs/en/reference/errors/content-collection-missing-loader.mdx

src/content/docs/en/reference/errors/legacy-content-config-error.mdx

src/content/docs/en/guides/upgrade-to/v6.mdx

… error messages

sarah11918 · 2025-09-26T12:03:05Z

Made some changes and resolved some conversations with explanations not to shut down further editing, just to tidy up and so we can work from something fresh now!

src/content/docs/en/guides/upgrade-to/v6.mdx

src/content/docs/en/reference/errors/content-collection-missing-loader.mdx

sarah11918 · 2025-10-17T13:53:40Z

I think all the pieces are here, and I did some minor polishing. Time to review again! Note that there ARE error messages in the astro repo errors.ts file, and these somewhat mirror them. We can deal with any slight discrepancies when we merge that branch into this branch.

NB: as noted above, any updating of the actual content collections guide page itself will come with the stabilization of Live Collections. Since non-legacy (current, non-live) collections are the main game in town, our current content collections page needs no updating to correspond to the loss of legacy collections.

ArmandPhilippot

Looks great, I left a few comments but those are mostly nitpicks!

src/content/docs/en/guides/upgrade-to/v6.mdx

src/content/docs/en/reference/legacy-flags.mdx

src/content/docs/en/guides/upgrade-to/v6.mdx

Co-authored-by: Armand Philippot <[email protected]>

src/content/docs/en/guides/upgrade-to/v6.mdx

…ed by Yan Co-authored-by: Yan <[email protected]>

sarah11918 · 2025-10-20T09:53:15Z

Going to consider this one acceptable enough to merge! I searched, but couldn't find any related error messages to not having a config file, nor using the older render method, so I think otherwise, this is good to go!

Still lots of time to make updates if we notice them, but this way, this content is merged and we can link to it in the preview of the upgrade guide.

removed content collections

3d722b8

sarah11918 added the 6.0 label Sep 22, 2025

sarah11918 added this to the v6.0.0 docs milestone Sep 22, 2025

sarah11918 and others added 8 commits September 22, 2025 09:12

Merge branch 'v6' into content-collections-removed

07221b6

links back to v5 content

ea94f56

proper link syntax

2471a2b

Merge branch 'v6' into content-collections-removed

9ff6f61

remove legacy flag documentation

fddbb86

🌭 details? do we like this?

fb4c121

add the implementation PR and some stronger wording

29fb6aa

add removing legacy flag

41f864b

sarah11918 changed the title ~~Content collections removed~~ support for legacy content collections removed Sep 24, 2025

ascorbic reviewed Sep 24, 2025

View reviewed changes

ArmandPhilippot reviewed Sep 25, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Show resolved Hide resolved

sarah11918 commented Sep 25, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

sarah11918 and others added 2 commits September 25, 2025 13:10

don't focus on collection API names, just legacy/new

1a71b64

Co-authored-by: Matt Kane <[email protected]>

add placeholder error messages

e849055

sarah11918 commented Sep 25, 2025

View reviewed changes

src/content/docs/en/reference/errors/content-collection-invalid-type.mdx Outdated Show resolved Hide resolved

sarah11918 commented Sep 25, 2025

View reviewed changes

src/content/docs/en/reference/errors/content-collection-missing-loader.mdx Outdated Show resolved Hide resolved

sarah11918 commented Sep 25, 2025

View reviewed changes

src/content/docs/en/reference/errors/legacy-content-config-error.mdx Outdated Show resolved Hide resolved

sarah11918 commented Sep 25, 2025

View reviewed changes

src/content/docs/en/reference/errors/legacy-content-config-error.mdx Outdated Show resolved Hide resolved

relative links

171c416

sarah11918 commented Sep 25, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

links to Content Layer API deep dive blog post and content collection…

5adf67e

… error messages

sarah11918 marked this pull request as ready for review September 26, 2025 13:12

Merge branch 'v6' into content-collections-removed

be4b2c1

sarah11918 commented Oct 17, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

sarah11918 commented Oct 17, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

sarah11918 commented Oct 17, 2025

View reviewed changes

src/content/docs/en/reference/errors/content-collection-missing-loader.mdx Outdated Show resolved Hide resolved

Polishing of upgrade guidance, fix an error message

b342d32

sarah11918 requested review from ArmandPhilippot, ascorbic and yanthomasdev October 17, 2025 13:48

ArmandPhilippot approved these changes Oct 17, 2025

View reviewed changes

sarah11918 and others added 2 commits October 18, 2025 08:04

Apply suggestions from Armand code review

192934b

Co-authored-by: Armand Philippot <[email protected]>

added error messages to summaries of things to check for

147afa5

sarah11918 commented Oct 18, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

sarah11918 commented Oct 18, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

fix links

9bb8dc3

sarah11918 commented Oct 18, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

fix error link

935b6d6

sarah11918 commented Oct 18, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

missing parenthesis

4649681

yanthomasdev reviewed Oct 18, 2025

View reviewed changes

src/content/docs/en/guides/upgrade-to/v6.mdx Outdated Show resolved Hide resolved

sarah11918 and others added 2 commits October 18, 2025 11:22

two commas, but one line suggestion so I'm declaring it ONE error fix…

01342b0

…ed by Yan Co-authored-by: Yan <[email protected]>

Merge branch 'v6' into content-collections-removed

7f20e74

sarah11918 merged commit ab8cf68 into v6 Oct 20, 2025
10 checks passed

sarah11918 deleted the content-collections-removed branch October 20, 2025 09:55


		If you have content collections errors after upgrading to v6, use the following list to help you identify and upgrade any legacy features that may exist in your code.

		##### If you have...

Uh oh!

support for legacy content collections removed #12376

support for legacy content collections removed #12376

Uh oh!

Conversation

sarah11918 commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for astro-docs-2 ready!

Uh oh!

astrobot-houston commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Lunaria Status Overview

Tracked Files

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarah11918 Sep 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 commented Sep 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 commented Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ArmandPhilippot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarah11918 commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

sarah11918 commented Sep 22, 2025 •

edited

Loading

netlify bot commented Sep 22, 2025 •

edited

Loading

astrobot-houston commented Sep 22, 2025 •

edited

Loading

sarah11918 Sep 25, 2025 •

edited

Loading

sarah11918 Sep 26, 2025 •

edited

Loading

sarah11918 commented Oct 17, 2025 •

edited

Loading

sarah11918 commented Oct 20, 2025 •

edited

Loading